Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.4.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.swing
Class TransferHandler

    java.lang.Object
      |
      +--javax.swing.TransferHandler

All Implemented Interfaces:
  Serializable

public class TransferHandler
extends Object
implements Serializable

This class is used to handle the transfer of a `Transferable` to and from Swing components. The `Transferable` is used to represent data that is exchanged via a cut, copy, or paste to/from a clipboard. It is also used in drag-and-drop operations to represent a drag from a component, and a drop to a component. Swing provides functionality that automatically supports cut, copy, and paste keyboard bindings that use the functionality provided by an implementation of this class. Swing also provides functionality that automatically supports drag and drop that uses the functionality provided by an implementation of this class. The Swing developer can concentrate on specifying the semantics of a transfer primarily by setting the `transferHandler` property on a Swing component.

This class is implemented to provide a default behavior of transferring a component property simply by specifying the name of the property in the constructor. For example, to transfer the foreground color from one component to another either via the clipboard or a drag and drop operation a `TransferHandler` can be constructed with the string "foreground". The built in support will use the color returned by `getForeground` as the source of the transfer, and `setForeground` for the target of a transfer.

Field Summary
`static int` | `COPY` An `int` representing a "copy" transfer action.
`static int` | `COPY_OR_MOVE` An `int` representing a source action capability of either "copy" or "move".
`static int` | `MOVE` An `int` representing a "move" transfer action.
`static int` | `NONE` An `int` representing no transfer action.

Constructor Summary
`protected` | `TransferHandler()` Convenience constructor for subclasses.
`` | `TransferHandler(String property)` Constructs a transfer handler that can transfer a Java Bean property from one component to another via the clipboard or a drag and drop operation.

Method Summary
`boolean` | `canImport(JComponent comp, DataFlavor[] transferFlavors)` Indicates whether a component would accept an import of the given set of data flavors prior to actually attempting to import it.
`protected Transferable` | `createTransferable(JComponent c)` Creates a `Transferable` to use as the source for a data transfer.
`void` | `exportAsDrag(JComponent comp, InputEvent e, int action)` Causes the Swing drag support to be initiated.
`protected void` | `exportDone(JComponent source, Transferable data, int action)` Invoked after data has been exported.
`void` | `exportToClipboard(JComponent comp, Clipboard clip, int action)` Causes a transfer from the given component to the given clipboard.
`static Action` | `getCopyAction()` Returns an `Action` that behaves like a 'copy' operation.
`static Action` | `getCutAction()` Returns an `Action` that behaves like a 'cut' operation.
`static Action` | `getPasteAction()` Returns an `Action` that behaves like a 'paste' operation.
`int` | `getSourceActions(JComponent c)` Returns the type of transfer actions supported by the source.
`Icon` | `getVisualRepresentation(Transferable t)` Returns an object that establishes the look of a transfer.
`boolean` | `importData(JComponent comp, Transferable t)` Causes a transfer to a component from a clipboard or a DND drop operation.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### NONE

    public static final int NONE

  An `int` representing no transfer action.

  See Also:
    Constant Field Values

### COPY

    public static final int COPY

  An `int` representing a "copy" transfer action. This value is used when data is copied to a clipboard or copied elsewhere in a drag and drop operation.

  See Also:
    Constant Field Values

### MOVE

    public static final int MOVE

  An `int` representing a "move" transfer action. This value is used when data is moved to a clipboard (i.e. a cut) or moved elsewhere in a drag and drop operation.

  See Also:
    Constant Field Values

### COPY_OR_MOVE

    public static final int COPY_OR_MOVE

  An `int` representing a source action capability of either "copy" or "move".

  See Also:
    Constant Field Values

Constructor Detail

### TransferHandler

    public TransferHandler(String property)

  Constructs a transfer handler that can transfer a Java Bean property from one component to another via the clipboard or a drag and drop operation.

Parameters:
  `property` - the name of the property to transfer; this can be `null` if there is no property associated with the transfer handler (a subclass that performs some other kind of transfer, for example)

### TransferHandler

    protected TransferHandler()

  Convenience constructor for subclasses.

Method Detail

### getCutAction

    public static Action getCutAction()

  Returns an `Action` that behaves like a 'cut' operation. That is, this will invoke `exportToClipboard` with a `MOVE` argument on the `TransferHandler` associated with the `JComponent` that is the source of the `ActionEvent`.

  Returns:
    cut Action

### getCopyAction

    public static Action getCopyAction()

  Returns an `Action` that behaves like a 'copy' operation. That is, this will invoke `exportToClipboard` with a `COPY` argument on the `TransferHandler` associated with the `JComponent` that is the source of the `ActionEvent`.

  Returns:
    cut Action

### getPasteAction

    public static Action getPasteAction()

  Returns an `Action` that behaves like a 'paste' operation. That is, this will invoke `importData` on the `TransferHandler` associated with the `JComponent` that is the source of the `ActionEvent`.

  Returns:
    cut Action

### exportAsDrag

    public void exportAsDrag(JComponent comp,
                             InputEvent e,
                             int action)

  Causes the Swing drag support to be initiated. This is called by the various UI implementations in the `javax.swing.plaf.basic` package if the dragEnabled property is set on the component. This can be called by custom UI implementations to use the Swing drag support. This method can also be called by a Swing extension written as a subclass of `JComponent` to take advantage of the Swing drag support.

  The transfer will not necessarily have been completed at the return of this call (i.e. the call does not block waiting for the drop). The transfer will take place through the Swing implementation of the `java.awt.dnd` mechanism, requiring no further effort from the developer. The `exportDone` method will be called when the transfer has completed.

  Parameters:
    `comp` - the component holding the data to be transferred; this argument is provided to enable sharing of `TransferHandler`s by multiple components
    `e` - the event that triggered the transfer
    `action` - the transfer action initially requested; this should be a value of either `COPY` or `MOVE`; the value may be changed during the course of the drag operation

### exportToClipboard

    public void exportToClipboard(JComponent comp,
                                  Clipboard clip,
                                  int action)

  Causes a transfer from the given component to the given clipboard. This method is called by the default cut and copy actions registered in a component's action map.

  The transfer will have been completed at the return of this call. The transfer will take place using the `java.awt.datatransfer` mechanism, requiring no further effort from the developer. The `exportDone` method will be called when the transfer has completed.

  Parameters:
    `comp` - the component holding the data to be transferred; this argument is provided to enable sharing of `TransferHandler`s by multiple components
    `clip` - the clipboard to transfer the data into
    `action` - the transfer action requested; this should be a value of either `COPY` or `MOVE`; the operation performed is the intersection of the transfer capabilities given by getSourceActions and the requested action; the intersection may result in an action of `NONE` if the requested action isn't supported

### importData

    public boolean importData(JComponent comp,
                              Transferable t)

  Causes a transfer to a component from a clipboard or a DND drop operation. The `Transferable` represents the data to be imported into the component.

  Parameters:
    `comp` - the component to receive the transfer; this argument is provided to enable sharing of `TransferHandler`s by multiple components
    `t` - the data to import
  Returns:
    true if the data was inserted into the component, false otherwise

### canImport

    public boolean canImport(JComponent comp,
                             DataFlavor[] transferFlavors)

  Indicates whether a component would accept an import of the given set of data flavors prior to actually attempting to import it.

  Parameters:
    `comp` - the component to receive the transfer; this argument is provided to enable sharing of `TransferHandlers` by multiple components
    `transferFlavors` - the data formats available
  Returns:
    true if the data can be inserted into the component, false otherwise

### getSourceActions

    public int getSourceActions(JComponent c)

  Returns the type of transfer actions supported by the source. Some models are not mutable, so a transfer operation of `COPY` only should be advertised in that case.

  Parameters:
    `c` - the component holding the data to be transferred; this argument is provided to enable sharing of `TransferHandler`s by multiple components.
  Returns:
    `COPY` if the transfer property can be found, otherwise returns `NONE`; a return value of of `NONE` disables any transfers out of the component

### getVisualRepresentation

    public Icon getVisualRepresentation(Transferable t)

  Returns an object that establishes the look of a transfer. This is useful for both providing feedback while performing a drag operation and for representing the transfer in a clipboard implementation that has a visual appearance. The implementation of the `Icon` interface should not alter the graphics clip or alpha level. The icon implementation need not be rectangular or paint all of the bounding rectangle and logic that calls the icons paint method should not assume the all bits are painted. `null` is a valid return value for this method and indicates there is no visual representation provided. In that case, the calling logic is free to represent the transferable however it wants.

  The default Swing logic will not do an alpha blended drag animation if the return is `null`.

  Parameters:
    `t` - the data to be transferred; this value is expected to have been created by the `createTransferable` method
  Returns:
    `null`, indicating there is no default visual representation

### createTransferable

    protected Transferable createTransferable(JComponent c)

  Creates a `Transferable` to use as the source for a data transfer. Returns the representation of the data to be transferred, or `null` if the component's property is `null`

  Parameters:
    `c` - the component holding the data to be transferred; this argument is provided to enable sharing of `TransferHandler`s by multiple components
  Returns:
    the representation of the data to be transferred, or `null` if the property associated with `c` is `null`

### exportDone

    protected void exportDone(JComponent source,
                              Transferable data,
                              int action)

  Invoked after data has been exported. This method should remove the data that was transferred if the action was `MOVE`.

  This method is implemented to do nothing since `MOVE` is not a supported action of this implementation (`getSourceActions` does not include `MOVE`).

  Parameters:
    `source` - the component that was the source of the data
    `data` - The data that was transferred or possibly null if the action is `NONE`.
    `action` - the actual action that was performed

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| JavaTM 2 Platform Std. Ed. v1.4.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2002 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.